Read-only MCP server for U.S. dental practice intelligence. Four tools cover NPI lookup, multi-field provider search, DSO chain affiliation, and territory market summaries across 41 states plus DC. Authenticate with an API key (Bearer) for subscription pricing, or pay per query via x402 USDC micropayments on Base mainnet. Every response carries a citation envelope with source attribution, snapshot date, and confidence score.
概要
API
MCP server for U.S. dental provider data
Model Context Protocol endpoint at mcp.providersignal.com. Four read-only tools, citation envelope on every response, two billing rails (Bearer subscription or per-call USDC). Compatible with Claude.ai, Cursor, ChatGPT, and any MCP-aware client.
EndpointToolsAuth & BillingResponse ShapeInput ValidationRate LimitsDiscoveryConnect a ClientReferencesFull API reference →
Endpoint
Streamable HTTP transport per the Model Context Protocol spec. POST JSON-RPC 2.0 messages to:
Discovery manifest (no auth required) at:
MCP protocol version implemented: 2025-06-18. Notifications return HTTP 204; batched JSON-RPC requests are supported.
Tools (4 read-only)
Each MCP tool maps to one path under /api/v1/agent. Every response is wrapped in a citation envelope (see Response Shape).
lookup_provider_by_npi(npi)
forwards to /api/v1/agent/lookup-by-npi
Full provider record by 10-digit NPI. Returns name, taxonomy, practice address, license metadata, DSO flag, OIG-exclusion flag, lat/lon, CMS-claims flag, and a 0-100 confidence score. ~30 fields total.
search_providers({state, city, zip, license_status, page, per_page})
forwards to /api/v1/agent/search
Filtered list with pagination. Filters compose with AND. per_page caps at 100. Returns the same envelope shape as lookup with a compact per-row record array.
get_dso_affiliation(npi)
forwards to /api/v1/agent/dso/affiliation
Dental Service Organization affiliation lookup. Returns the inferred parent brand, signal type (parent_org, multi_location, address_cascade, or shared_phone_org), confidence, cluster size, and a sibling NPI sample.
get_territory_summary({state, zip})
forwards to /api/v1/agent/territory/rollup
Aggregate market intelligence for a geography. Returns total provider count, DSO penetration share, retirement-risk-55-plus count, license-status breakdown, and organization count.
Full input schemas (JSON Schema for every parameter) are served by the tools/list JSON-RPC method. The discovery manifest carries the short-form descriptions only.
Auth and billing
Two billing rails. Pick one based on your agent framework and use case.
Rail 1: Bearer-token subscription (default for MCP today)
Pass an existing ProviderSignal API key on every request:
Per-call usage rides your subscription tier's rate limit. Pro and Rep tiers cap at 500 req/min. Team and Growth at 200/min. Enterprise tiers run higher. The MCP server also enforces a 60 req/min IP-level limit before any token validation, so anonymous probes never reach the database.
Get a key from your dashboard API keys page.
Rail 2: per-call USDC via x402 (advertised in the manifest)
Skip the subscription and call the underlying endpoints directly at https://providersignal.com/api/v1/agent/*. The first request returns 402 with PaymentRequirements. Sign a USDC transfer on Base mainnet and retry with X-PAYMENT. See /docs/agent-payments for the full flow.
Native MCP-side x402 (a 402 challenge inside a tool call) is a v1.1 deferred item. Most MCP clients do not yet implement the tool-call payment-challenge loop. Until they do, the x402 path is reachable outside MCP via the direct /api/v1/agent/* endpoints.
Response shape
Every tool returns a JSON-RPC result with a single content array carrying the citation envelope as text:
Initialize
List tools
Call a tool
Tool response (truncated)
The envelope inside content[0].text carries:
datapayload (provider record, search results, or aggregate)meta.source_attributionarray. One entry per data table touched, withlast_refresh,schema_version, and license posture.meta.confidence.provider_recordwith a 0-100 score and breakdown (completeness, multi_source, freshness).meta.requestwith the request id, endpoint, billed_credits, and billing_method (subscription or per_query).
The full field glossary lives at /docs/fields.
Input validation
Tool arguments are validated at the edge before any database call. Validation errors return JSON-RPC -32602 (invalid params) and never burn rate-limit quota or hit Supabase. Defense in depth: the main API re-validates everything server side.
- npi:
/^\d{10}$/ - state:
/^[A-Z]{2}$/ - zip:
/^\d{5}(-\d{4})?$/(5- or 9-digit) - license_status: enum (active, inactive, expired, retired, deceased)
- page: integer 1 to 10000
- per_page: integer 1 to 100
- strings: 200 chars max (city: 80 max)
Rate limits and body cap
Three guard rails:
- 60 req/min per IP at the MCP edge, enforced by Upstash Redis sliding window. Fires before any auth or parse work, so anonymous probes cost almost nothing.
- 16 KB body cap via Content-Length. Larger requests return HTTP 413 before parse.
- Per-key rate limit from your subscription tier (Pro 500/min, Team and Growth 200/min, Enterprise higher). Enforced after key validation.
When you hit a 429 you get a retry_after_seconds hint plus standard X-RateLimit- response headers.
Discovery manifest
The .well-known/mcp.json manifest is the 2026 MCP-discovery convention. MCP-aware clients fetch it on connect and render the results in their connector picker. Our manifest advertises:
- Server name, version, protocol version
- Transport: streamable-http at
/mcp - Primary auth: bearer (link to dashboard for key issuance)
alternateBillingblock: x402 protocol details, network (Base mainnet eip155:8453), USDC asset, full price ladder, OpenAPI link.- Tool list with names and short descriptions
- Homepage, documentation, contact, license, publisher
Hit it directly:
Connect a client
Claude.ai
- Settings, then Connectors, then Add custom connector
- URL:
https://mcp.providersignal.com/mcp - Bearer token: paste your
ps_live_key - Save
Claude probes the discovery manifest, registers the four tools, and lists them as available actions in any conversation.
Cursor and ChatGPT
Both support custom MCP connectors over HTTP. Use the same URL plus Bearer token through each client's custom-connector interface.
Custom agent code
Open a POST stream to the endpoint with your Bearer header. Send initialize, then tools/list, then tools/call per the MCP spec. JSON-RPC 2.0 batches are supported.
サーバー設定
{
"mcpServers": {
"providersignal": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.providersignal.com",
"--header",
"Authorization: Bearer ${PROVIDERSIGNAL_API_KEY}"
],
"env": {
"PROVIDERSIGNAL_API_KEY": "<YOUR_PS_LIVE_KEY>"
}
}
}
}